Description

Extends prompt caching TTL coverage beyond the user-supplied cachePoint path (already fixed in #1660) to the two SDK-managed auto-injected paths on BedrockModel.

Previously, only cache points that users passed directly inside message content could carry a ttl field — the formatter preserved it end-to-end. However, when the SDK auto-injected cache points on the user's behalf, the ttl was hardcoded away:

1. cache_tools — BedrockModel(cache_tools="default") appends {"cachePoint": {"type": "default"}} to toolConfig.tools with no way to set a TTL.
2. _inject_cache_point — when cache_config=CacheConfig(strategy="auto") is set, the SDK appends {"cachePoint": {"type": "default"}} to the last user message with no way to set a TTL.

Because Bedrock processes cache checkpoints in order toolConfig → system → messages and requires TTLs to be non-increasing, a user who wanted to run 1h caching end-to-end could not — the SDK-managed checkpoints would implicitly be 5m and violate the ordering rule (see #2121 Bug 2).

Changes

• BedrockModel: added cache_tools_ttl: str | None config option. When set together with cache_tools, the TTL is propagated into the toolConfig cache point.
• CacheConfig: added ttl: str | None field. When set, _inject_cache_point includes the TTL in the cache point appended to the last user message.

Users can now align all three cache checkpoint TTLs consistently:

from strands.models.bedrock import BedrockModel
from strands.models.model import CacheConfig

model = BedrockModel(
    model_id="us.anthropic.claude-haiku-4-5-20251001-v1:0",
    cache_tools="default",
    cache_tools_ttl="1h",
    cache_config=CacheConfig(strategy="auto", ttl="1h"),
)

API reference: https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_CachePointBlock.html
Launch announcement: https://aws.amazon.com/about-aws/whats-new/2026/01/amazon-bedrock-one-hour-duration-prompt-caching/

Related Issues

Partially addresses #2121 (Bug 2: cache_tools ordering violation with 1h TTL).

Bug 1 from #2121 (user-supplied ttl being dropped) was resolved by #1660.

Documentation PR

Type of Change

New feature

Testing

Added 4 unit tests:

• test_inject_cache_point_with_ttl — verifies CacheConfig(ttl="5m") propagates into the auto-injected message cache point.
• test_inject_cache_point_without_ttl — backward compat: CacheConfig(strategy="auto") with no TTL still works.
• test_format_request_cache_tools_with_ttl — verifies cache_tools_ttl propagates into toolConfig cache point.
• test_format_request_cache_tools_without_ttl — backward compat: cache_tools without TTL still works.

Verified:

• I ran hatch run prepare (lint, format, mypy all clean; pre-existing local env test failures unrelated to this change)
• All 4 new tests pass

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.